# Migrating FingerprintJS v3 to v4

This guide shows how to migrate your code from FingerprintJS version 3 to version 4.
The API and the installations methods are almost the same in both version.

## License

Please note that our **licensing terms for v4 has changed**. The table below indicates the different use-cases that shall require a commercial license to be purchased.

| | Before license change (versions 3.x and lower) | After license change (versions 4.x and higher) |
|----------|----------|----------|
| License | [MIT](https://opensource.org/license/mit/) | [BSL 1.1](../../LICENSE) |
| Use FingerprintJS for research, explorative and all other non-commercial purposes | ✅ | ✅ |
| Fork FingerprintJS repository for production | ✅ | ❌ (requires a commercial license to be purchased) |
| Use FingerprintJS in production | ✅ | ❌ (requires a commercial license to be purchased) |

To purchase a license for uses not authorized by BSL, please contact us at [sales@fingerprint.com](mailto:sales@fingerprint.com?subject=Interested%20in%20FingerprintJS%20commercial%20license).

## Installation

The migration process depends on the way you install the library.

### CDN

Change the version number in the URL from `3` to `4`. For example:

```diff
- https://openfpcdn.io/fingerprintjs/v3/iife.min.js
+ https://openfpcdn.io/fingerprintjs/v4/iife.min.js
```

### NPM or Yarn

Update the package version:

```bash
npm install @fingerprintjs/fingerprintjs
# or
yarn add @fingerprintjs/fingerprintjs
```

## API

### Entropy source unexpected error handling

If you don't handle errors in `components` field of `get()` result, skip this section.

In version 3 unexpected entropy source errors were coerced to a `{ message: any }` object,
so that the `error` field of a component object is always truthy in case of unexpected error.

In version 4 the caught error is put into the `error` field as is.
The presence of error should be checked using the `'error' in component` syntax:

```diff
- if (component.error) {
+ if ('error' in component) {
    console.log('Unexpected error in the component', component.error)
  }
```

TypeScript supports type-guarding using `in` keyword since [version 4.9](https://devblogs.microsoft.com/typescript/announcing-typescript-4-9/#in-narrowing),
so the above code snippet works in TypeScript just fine.

This example shows the `get()` result difference in case when the error is a falsy value, which is very unlikely:

```diff
const result = {
  visitorId: '...',
  components: {
    failedComponent: {
-     error: { message: '' },
+     error: '',
      duration: 10,
    },
  },
  // ...
}
```

## How to update without losing the identifiers

The process is the same as for minor version update.
See the [version policy guide](../version_policy.md#how-to-update-without-losing-the-identifiers).
